package com.zenithmind.user.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.common.result.PageResult;
import com.zenithmind.common.result.Result;
import com.zenithmind.user.pojo.domain.VerificationCode;
import com.zenithmind.user.pojo.dto.VerificationRequestDTO;
import com.zenithmind.user.pojo.query.VerificationCodeQuery;
import com.zenithmind.user.pojo.vo.VerificationCodeVO;

import java.util.List;
import java.util.Map;

/**
 * 验证码服务接口
 */
public interface VerificationCodeService extends IService<VerificationCode> {
    
    /**
     * 生成验证码（使用DTO）
     * 
     * @param verificationRequestDTO 验证码请求DTO
     */
    void generateCode(VerificationRequestDTO verificationRequestDTO);
    
    /**
     * 生成验证码
     * 
     * @param username 用户名
     * @param email 邮箱地址
     */
    void generateCode(String username, String email);
    
    /**
     * 生成验证码（带IP地址）
     * 
     * @param username 用户名
     * @param email 邮箱地址
     * @param ipAddress IP地址
     */
    void generateCode(String username, String email, String ipAddress);
    
    /**
     * 发送登录验证码（使用DTO）
     * 
     * @param verificationRequestDTO 验证码请求DTO
     * @return 发送结果
     */
    Result<Void> sendLoginVerificationCode(VerificationRequestDTO verificationRequestDTO);
    
    /**
     * 发送登录验证码
     * 
     * @param username 接收验证码的用户名
     * @return 发送结果
     */
    Result<Void> sendLoginVerificationCode(String username);
    
    /**
     * 验证验证码（使用DTO）
     * 
     * @param verificationRequestDTO 验证码请求DTO
     * @return 验证结果
     */
    boolean verifyCode(VerificationRequestDTO verificationRequestDTO);
    
    /**
     * 验证验证码
     * 
     * @param username 用户名
     * @param code 验证码
     * @return 验证结果
     */
    boolean verifyCode(String username, String code);
    
    /**
     * 设置验证码类型（使用DTO）
     * 
     * @param verificationRequestDTO 验证码请求DTO
     * @return 设置结果
     */
    boolean setCodeType(VerificationRequestDTO verificationRequestDTO);
    
    /**
     * 设置验证码类型
     * 
     * @param username 用户名
     * @param type 验证码类型(0:登录,1:注册,2:重置密码)
     * @return 设置结果
     */
    boolean setCodeType(String username, Integer type);
    
    /**
     * 查询用户验证码历史（使用DTO）
     * 
     * @param verificationRequestDTO 验证码请求DTO
     * @return 验证码记录列表
     */
    List<VerificationCode> getUserVerificationHistory(VerificationRequestDTO verificationRequestDTO);
    
    /**
     * 查询用户验证码历史
     * 
     * @param username 用户名
     * @param limit 查询数量限制
     * @return 验证码记录列表
     */
    List<VerificationCode> getUserVerificationHistory(String username, int limit);
    
    /**
     * 手动清理过期验证码
     * 
     * @return 清理数量
     */
    int cleanExpiredCodes();
    
    /**
     * 分页查询验证码记录
     * 
     * @param verificationCodeQuery 验证码查询条件，包含分页信息和查询条件
     * @return 分页验证码记录
     */
    PageResult<VerificationCodeVO> pageVerificationCodes(VerificationCodeQuery verificationCodeQuery);
    
    /**
     * 统计验证码使用情况
     * 
     * @return 统计数据
     */
    Map<String, Object> getVerificationStatistics();

    VerificationCode addOrUpdateVerificationCode(VerificationCode verificationCode);
} 